=begin pod

=TITLE role Scheduler

=SUBTITLE Scheme for automatically assigning tasks to threads

    role Scheduler {
        has &.uncaught_handler is rw
    }

Common role for schedulers. A scheduler is a piece of code that determines
which resources to use to run which task, and when.

Some operations for example on L<Proc::Async>, L<Promise|/type/Promise>,
L<Supply|/type/Supply> allow you to specify a scheduler explicitly; they
generally expect those schedulers to follow the interface defined by
C<Scheduler>

=head1 Methods

=head2 method uncaught_handler

    method uncaught_handler() is rw

RW-Accessor for the handler that is caught for uncaught exceptions from the
code that is being scheduled and run.

=head2 method cue

    method cue(:&code, Instant :$at, :$in, :$every, :$times = 1; :&catch)

Schedules a callable (C<&code>) for execution. The adverbs control when and
how the code is run:

C<$at> can be an L<Instant|/type/Instant> before which the code won't be run.
Alternatively C<$in> is the number of seconds (possibly fractional) to wait
before running the code. If C<$at> is in the past or C<$in> is negative,
the delay is treated as zero. Implementations may equate to zero
very small values (e.g. lower than 0.001s) of C<$in> or result of
C<$at> - L<now>.

If C<$every> is specified, it is interpreted as the number of seconds
(possibly fractional) to wait before re-executing the code. Implementations
may treat too-small values as lowest resolution they support, possibly
warning in such situations; e.g. treating C<0.0001> as C<0.001>.

C<$times> tells the scheduler how many times to run the code.

C<&catch> is called with the L<Exception|/type/Exception> as its sole argument
if C<&code> dies.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
